Skip to content

docs(core): document PageScrollLockController like other 2nd-gen controllers - #6534

Merged
rubencarvalho merged 9 commits into
mainfrom
rcarvalho/refactor-page-scroll-lock-controller-structure
Aug 7, 2026
Merged

docs(core): document PageScrollLockController like other 2nd-gen controllers#6534
rubencarvalho merged 9 commits into
mainfrom
rcarvalho/refactor-page-scroll-lock-controller-structure

Conversation

@rubencarvalho

@rubencarvalho rubencarvalho commented Jul 20, 2026

Copy link
Copy Markdown
Contributor

Description

Moves PageScrollLockController into the standard 2nd-gen controller folder layout (controllers/page-scroll-lock-controller/{index.ts,src/,stories/,test/,page-scroll-lock-controller.mdx}), matching color-controller, hover-controller, pending-controller, etc. No behavior change to the controller.

Adds:

  • A Storybook docs page with usage, behavior, and accessibility guidance
  • One demo host with a native lock/unlock toggle button
  • A functional test covering reference-counted stacking, idempotency, and disconnect cleanup
  • A ./controllers/page-scroll-lock-controller.js package export

Motivation and context

This was the only 2nd-gen controller without a folder, stories, or docs page.

Related issue(s)

  • No tracked issue; documentation/organization cleanup.

Screenshots (if appropriate)

N/A — docs-only change.

Author's checklist

  • I have read the CONTRIBUTING and PULL_REQUESTS documents.
  • I have reviewed at the Accessibility Practices for this feature, see: Aria Practices
  • I have added automated tests to cover my changes.
  • I have included a well-written changeset if my change needs to be published.
  • I have included updated documentation if my change required it.

Reviewer's checklist

  • Includes a Github Issue with appropriate flag or Jira ticket number without a link
  • Includes thoughtfully written changeset if changes suggested include patch, minor, or major features
  • Automated tests cover all use cases and follow best practices for writing
  • Validated on all supported browsers
  • All VRTs are approved before the author can update Golden Hash

Manual review test cases

  • Docs page renders

    1. Go to Storybook, Controllers/Page scroll lock controller
    2. Confirm Overview, Behaviors, and Accessibility sections render with no console errors
  • Lock/unlock toggle

    1. Click "Lock page scroll" in the Overview demo — canvas becomes unscrollable
    2. Click "Unlock page scroll" — scroll is restored

Device review

  • Did it pass in Desktop?
  • Did it pass in (emulated) Mobile?
  • Did it pass in (emulated) iPad?

Accessibility testing checklist

  • Keyboard (required — document steps below)

    1. Demo toggle is a native <button>; activates with Enter/Space
    2. Controller itself is unchanged, so existing consumers (e.g. swc-popover) see no keyboard regressions
  • Screen reader (required — document steps below)

    1. Controller sets no ARIA and manages no focus; it only toggles overflow on document.documentElement
    2. No announcement changes for existing consumers

…rollers

Move the controller from a bare file into the standard controller folder
layout (index.ts, src/, stories/, test/, .mdx) so it gets Storybook docs
and demo stories like every other 2nd-gen controller. Wires the new export
path into core/package.json.
@rubencarvalho
rubencarvalho requested a review from a team as a code owner July 20, 2026 21:07
@changeset-bot

changeset-bot Bot commented Jul 20, 2026

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: 238e61f

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@github-actions

Copy link
Copy Markdown
Contributor

📚 Branch Preview Links

🔍 Gen1 Visual Regression Test Results

When a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:

Deployed to Azure Blob Storage: pr-6534

If the changes are expected, update the current_golden_images_cache hash in the circleci config to accept the new images. Instructions are included in that file.
If the changes are unexpected, you can investigate the cause of the differences and update the code accordingly.

@rubencarvalho
rubencarvalho marked this pull request as draft July 20, 2026 21:22
Drop the separate status readout component and the two-host stacked-locks
story. One host with a lock/unlock toggle is enough to demonstrate the
controller, which has no host interface requirement of its own.
rubencarvalho and others added 2 commits August 7, 2026 11:17
…r page

Behaviors and Accessibility rendered the exact same lock/unlock toggle as
Overview, so the docs page repeated one live demo three times. Keep the
section headings and prose but drop the duplicate Canvas instances, and
strip the demo button's custom styles since native button styling is enough.
@rubencarvalho
rubencarvalho marked this pull request as ready for review August 7, 2026 10:57
@rubencarvalho rubencarvalho added Component:Documentation Issues or PRs involving changes to docs or docs website. Component prefix is for Jira integration. Status:Ready for review PR ready for review or re-review. gen2 These issues or PRs map to our 2nd generation work to modernizing infrastructure. labels Aug 7, 2026

@Rajdeepc Rajdeepc left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: If you can add an Accessibility story in this direction that would cover the entire flow.
add StackedLocks, two demo-scroll-lock-host instances side by side:

export const StackedLocks: Story = {
  render: () => html`
    <demo-scroll-lock-host></demo-scroll-lock-host>
    <demo-scroll-lock-host></demo-scroll-lock-host>
    ${scrollFiller}
  `,
  tags: ['behaviors'],
  parameters: { flexLayout: 'row-wrap' },
};
StackedLocks.storyName = 'Stacked locks';

Proves reference counting: lock A, lock B, unlock A (still locked), unlock B (now unlocked). Add under ### Lock and unlock in the MDX.

Accessibility story — just needs to exist so the MDX Canvas has a target:

export const Accessibility: Story = {
  tags: ['a11y'],
};

Then add at the end of ## Accessibility in the MDX.

@rubencarvalho rubencarvalho added the skip_vrt Skip VRT build; mark UI Tests green without running Chromatic label Aug 7, 2026
@rubencarvalho
rubencarvalho enabled auto-merge (squash) August 7, 2026 15:22
@rubencarvalho
rubencarvalho merged commit 70c3af5 into main Aug 7, 2026
32 of 33 checks passed
@rubencarvalho
rubencarvalho deleted the rcarvalho/refactor-page-scroll-lock-controller-structure branch August 7, 2026 15:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Component:Documentation Issues or PRs involving changes to docs or docs website. Component prefix is for Jira integration. gen2 These issues or PRs map to our 2nd generation work to modernizing infrastructure. skip_vrt Skip VRT build; mark UI Tests green without running Chromatic Status:Ready for review PR ready for review or re-review.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants